JBoss.orgCommunity Documentation

Chapter 7. Logging, Traces and Alarms

7.1. Log4j Logging Service
7.1.1. Simplified Global Log4j Configuration
7.2. Alarms
7.3. Trace Facility
7.3.1. JAIN SLEE Tracers and Log4j

In Mobicents SIP Presence Apache log4j is used for logging. If you are not familiar with the log4j package and would like to use it in your applications, you can read more about it at the Jakarta web site.

Logging is controlled from a central conf/jboss-log4j.xml file in each server configuration profile. This file defines a set of appenders specifying the log files, what categories of messages should go there, the message format and the level of filtering. By default, Mobicents produces output to both the console and a log file (log/server.log).

There are 6 basic log levels used: TRACE, DEBUG, INFO, WARN, ERROR and FATAL.

Logging is organized into categories and appenders. Appenders control the destination of log entries. Different appenders differ in configuration, however each supports thresholds. Threshold filters log entries based on their level. A threshold set to WARN will allow log entries to pass into the appender if the level is WARN, ERROR or FATAL. Other entries will be discarded. For more details on appender configuration, please refer to its documentation or java doc.

The logging threshold on the console is INFO by default. However, there is no threshold set for the server.log file, so all generated logging messages are logged there.

Categories control the level for loggers and its children. For details, please refer to the log4j manual.

By default, Mobicents SIP Presence inherits a level of INFO from the root logger. To make the platform add more detailed logs, the conf/jboss-log4j.xml file has to be altered. Explicit category definition for Mobicents SIP Presence looks like:



<category name="org.mobicents.slee"> 
    <priority value="INFO"/> 
</category>
        

This limits the level of logging to INFO for all Mobicents SIP Presence classes. It is possible to declare more categories with different levels, to provide logs with greater detail.

For instance, to provide detailed information on the Mobicents SIP Presence transaction engine in a separate log file (txmanager.log), the conf/jboss-log4j.xml file should contain entries as follows:



<appender name="TXMANAGER" class="org.jboss.logging.appender.RollingFileAppender"> 
    <errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/> 
    <param name="File" value="${jboss.server.home.dir}/log/txmanager.log"/> 
    <param name="Append" value="false"/> 
    <param name="MaxFileSize" value="500KB"/> 
    <param name="MaxBackupIndex" value="1"/> 
 
    <layout class="org.apache.log4j.PatternLayout"> 
        <param name="ConversionPattern" value="%d %-5p [%c] %m%n"/> 
    </layout> 
</appender> 
 
<category name="org.mobicents.slee.runtime.transaction"> 
    <priority value="DEBUG" /> 
    <appender-ref ref="TXMANAGER"/> 
</category>
        

This creates a new file appender and specifies that it should be used by the logger (or category) for the package org.mobicents.slee.runtime.transaction.

The file appender is set up to produce a new log file every day rather than producing a new one every time you restart the server or writing to a single file indefinitely. The current log file is txmanager.log. Older files have the date they were written added to their filenames.

Besides manual logging configuration, described previously, Mobicents SIP Presence also exposes management operations that greatly simplify such configuration, allowing the administrator to select from predefined and complete logging configuration presets. These operations are available in the org.mobicents.slee%3Aservice%3DMobicentsManagement MBean. The available presets are:

The available management operations are:

Custom presets can be easily deployed in the application server too. Simply name the configuration file as jboss-log4j.xml.PRESET_NAME, where PRESET_NAME should be a unique preset name, and copy it into the $JBOSS_HOME/server/profile_name/deploy/mobicents-slee/log4j-templates directory, where profile_name is the server profile name.

Currently Mobicents SIP Presence does not uses JAIN SLEE Alarms.

Notification sources such as SBBs, Resource Adaptors, Profiles, and SLEE internal components use the JAIN SLEE Trace Facility to generate trace messages intended for consumption by external management clients. Management clients register to receive trace messages generated by the Trace Facility through the external management interface (MBean). Filters can be applied in a similar way to Alarms.

Within the SLEE, notification sources use a tracer to emit trace messages. A tracer is a named entity. Tracer names are case-sensitive and follow the Java hierarchical naming conventions. A tracer is considered to be an ancestor of another tracer if its name followed by a dot is a prefix of the descendant tracer’s name. A tracer is considered to be a parent of a tracer if there are no ancestors between itself and the descendant tracer. For example, the tracer named com is the parent tracer of the tracer named com.foo and an ancestor of the tracer named com.foo.bar.

All tracers are implicitly associated with a notification source, which identifies the object in the SLEE that is emitting the trace message, and is included in trace notifications generated by the Trace MBean on behalf of the tracer. For instance, an SBB notification source is composed by the SBB ID and the Service ID.

For further information on how to use JAIN SLEE Trace Facility and receive JMX notifications refer to the JAIN SLEE 1.1 Specification.

Mobicents SIP Presence Tracers additionally log messages to Apache Log4j, being the log4j category, for notification source X, defined as javax.slee. concatenated with the X.toString().

For instance, the full log4j logger name for tracer named GoogleTalkBotSbb, of sbb notification source with SbbID[name=GoogleTalkBotSbb,vendor=mobicents,version=1.0] and ServiceID[name=GoogleTalkBotService,vendor=mobicents,version=1.0], would be javax.slee.SbbNotification[service=ServiceID[name=GoogleTalkBotService, vendor=mobicents,version=0.1], sbb=SbbID[name=GoogleTalkBotSbb,vendor=mobicents, version=0.1]].GoogleTalkBotSbb (without the spaces or breaks), which means a log4j category defining its level as DEBUG could be:



<category
    name="javax.slee.SbbNotification[service=ServiceID[name=GoogleTalkBotService,
    vendor=mobicents,version=0.1],sbb=SbbID[name=GoogleTalkBotSbb,
    vendor=mobicents,version=0.1]]"> 
    <priority value="DEBUG" /> 
</category> 
            

The relation of JAIN SLEE tracers and log4j loggers goes beyond log4j showing tracer's messages. Changing the tracer's log4j logger effective level changes the tracer level in SLEE, and vice-versa. Since JAIN SLEE tracer levels differ from log4j logger levels, the table below maps the two: